'\"macro stdmacro
.\"
.\" Copyright (c) 2019 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMSERIESSETUP 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmSeriesSetup\f1,
\f3pmSeriesSetSlots\f1,
\f3pmSeriesSetEventLoop\f1,
\f3pmSeriesSetConfiguration\f1,
\f3pmSeriesSetMetricRegistry\f1,
\f3pmSeriesClose\f1 \- fast, scalable time series services
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmwebapi.h>
.sp
int pmSeriesSetup(pmSeriesModule *\fImodule\fP,
'in +\w'int pmSeriesSetup('u
pmSeriesCallBacks\ *\fIcallbacks\fP,
void\ *\fIarg\fP);
.in
.sp
int pmSeriesSetSlots(pmSeriesModule *\fImodule\fP,
'in +\w'int pmSeriesSetSlots('u
void\ *\fIslots\fP);
.in
.br
int pmSeriesSetEventLoop(pmSeriesModule *\fImodule\fP,
'in +\w'int pmSeriesSetEventLoop('u
void\ *\fIuvloop\fP);
.in
.br
int pmSeriesSetConfiguration(pmSeriesModule *\fImodule\fP,
'in +\w'int pmSeriesSetConfiguration('u
struct\ dict\ *\fIconfig\fP);
.in
.br
int pmSeriesSetMetricRegistry(pmSeriesModule *\fImodule\fP,
'in +\w'int pmSeriesSetMetricRegistry('u
struct\ mmv_registry\ *\fIregistry\fP);
.in
.sp
int pmSeriesClose(pmSeriesModule *\fImodule\fP);
.sp
cc ... \-lpcp_web
.hy
.ad
.ft 1
.SH DESCRIPTION
The
.B pmSeriesSetup
and related API functions prepare an application for accessing the fast,
scalable time series querying functionality of the Performance Co-Pilot (PCP).
.PP
This functionality is provided through asynchronous APIs, which function in
an event-driven fashion.
The interfaces described here prepare a given time series
.IR module
which associates callback routines with certain asynchronous events that occur
as part of servicing time series requests.
.PP
As a general pattern, all interfaces in these APIs that need to invoke
.I callbacks
provided by the calling program will take an opaque (void * pointer) parameter,
.IR arg .
This pointer will be passed through unchanged and is typically used to access a
data structure maintaining state within the calling program.
.PP
Where asynchronous setup is required by
.B pmSeriesSetup
its completion will be indicated through use of the
.I on_setup
callback, which is part of the passed in
.B pmSeriesModule
structure.
This structure also provides for custom diagnostics handling, through the
.I on_info
callback.
These are self-explanatory, see
.I <pcp/pmwebapi.h>
for exact calling conventions.
.PP
The
.I callbacks
registered by
.B pmSeriesSetup
to handle events are as follows:
.TP 5
\fBpmSeriesMatchCallBack\fR \fIon_match\fR
When a time series query discovers time series identifiers that
match the query, the
.I on_match
callback will be called once for every series identifier (SID).
The SID is a unique 40-byte ASCII representation of a SHA hash.
.TP
\fBpmSeriesDescCallBack\fR \fIon_desc\fR
Metric descriptor requests from
.BR pmSeriesDescs (1)
will invoke this callback once for each series identifier.
.TP
\fBpmSeriesInstCallBack\fR \fIon_inst\fR
Instance identification callback \- internal (numeric) and
external (string) instance identifiers,
as well as time series and source (host) SHA1 identifiers.
Called once for each instance.
The associated series identifier is also provided to the callback.
.TP
\fBpmSeriesLabelCallBack\fR \fIon_labelmap\fR
Provides metric labels (name and value mappings) for each
series identifier passed to
.BR pmSeriesLabels (1).
.TP
\fBpmSeriesStringCallBack\fR \fIon_instance\fR
Provides an instance name for a call to
.BR pmSeriesInstances (1) \-
the callback is called once for each instance name.
The associated series identifier is also provided to the callback.
.TP
\fBpmSeriesStringCallBack\fR \fIon_context\fR
Provides a context name for a call to
.BR pmSeriesSources (1) \-
the callback is called once for each source (hostname or archive).
The associated source identifier is also provided to the callback.
.TP
\fBpmSeriesStringCallBack\fR \fIon_metric\fR
Provides a metric name for a call to
.BR pmSeriesMetrics (1) \-
the callback is called once for each metric name.
The associated series identifier is also provided to the callback.
.TP
\fBpmSeriesStringCallBack\fR \fIon_label\fR
Provides a label name for a call to
.BR pmSeriesLabels (1) \-
the callback is called once for each label name.
The associated series identifier is also provided to the callback.
.TP
\fBpmSeriesValueCallBack\fR \fIon_value\fR
Calls to the
.BR pmSeriesQuery
interface that provide a time window may result in values being
found for matching time series.
The
.I on_value
callback will be invoked once for each time series value, also
providing the sample timestamp (in both string and binary form,
as a time in nanoseconds since the epoch).
The associated series identifier is also provided to the callback.
.TP
\fBpmSeriesDoneCallBack\fR \fIon_done\fR
On completion of all asynchronous interfaces that return success
(zero return code), this callback will be called.
It provides a status code indicating overall success (zero) or
failure (negative PMAPI code) of the operation.
.PP
The helper functions
.B pmSeriesSetSlots
(key-value server),
.B pmSeriesSetEventLoop
(libuv),
.B pmSeriesSetConfiguration
(configuration file)
and
.B pmSeriesSetMetricRegistry
(MMV instrumentation)
interfaces provide a mechanism for passing in state for each of
the associated subsystems.
.PP
Finally, a call to
.B pmSeriesClose
is used to end services available from a series
.I module
previously established through
.BR pmSeriesSetup .
.PP
Within PCP, the
.BR pmproxy (1)
and
.BR pmseries (1)
utilities are the primary users of these interfaces, providing REST API
and command line time series query services respectively.
.SH DIAGNOSTICS
Where these functions return a status code, this is always zero on success.
On failure a negative PMAPI error code is returned.
.SH SEE ALSO
.BR pmproxy (1),
.BR pmlogger (1),
.BR pmseries (1),
.BR mmv_stats_registry (3),
.BR pmSeriesDescs (3),
.BR pmSeriesQuery (3),
.BR PMAPI (3)
and
.BR PMWEBAPI (3).

.\" control lines for scripts/man-spell
.\" +ok+ libuv SHA
.\" +ok+ on_instance on_labelmap on_context on_metric on_label on_match
.\" +ok+ on_setup on_value on_desc on_done on_info on_inst {all from callbacks}
.\" +ok+ pmwebapi {from #include <pcp/pmwebapi.h>}
.\" +ok+ dict {from struct dict}
